Updated documentation from hooks-its Change-Id: I0e4867cc676301435f92c919770a7e3f948dabc7
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md index 56f345b..f80859c 100644 --- a/src/main/resources/Documentation/config.md +++ b/src/main/resources/Documentation/config.md
@@ -96,76 +96,578 @@ When Gerrit gitweb is configured, an additional direct link from Bugzilla to GitWeb will be created, pointing exactly to the Git commit ID containing the Bugzilla bug ID. -Issues workflow automation --------------------------- -Bugzilla plugin is able to automate status transition on the issues based on -code-review actions performed on Gerrit; actions are performed on Bugzilla using -the username/password provided during Gerrit init. +Automatic comments and actions +------------------------------ -When using this possibility, the plugin assumes that gerrit.canonicalWebUrl is set. -If it is not, the plugin will throw exceptions. +Setting up which event in gerrit (E.g.: “Change Merged”, or “User +‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a change”) should causes +what action on the ITS (e.g.: “Set issue's status to ‘Resolved’”) is +configured through a xref:config-rule-base[rule base] in +`etc/its/action.config`. -Transition automation is driven by `$GERRIT_SITE/issue-state-transition.config` file. +To turn off the legacy event handling of older 'hooks-*' plugins and +stop unwanted legacy comments, add the following settings to the +'bugzilla' section of 'etc/gerrit.config': -Syntax of the status transition configuration file is the following: +---- +commentOnChangeAbandoned = false +commentOnChangeMerged = false +commentOnChangeRestored = false +commentOnChangeCreated = false +commentOnCommentAdded = false +commentOnPatchSetCreated = false +commentOnRefUpdatedGitWeb = false +---- - [action "<issue-status-action>"] - change=<change-action> - verified=<verified-value> - code-review=<code-review-value> -`<issue-status-action>` -: Action to perform on Bugzila issue when all the conditions in the stanza are met. - <issue-status-action> can be any of: - status STATUS - change the associated bug's status to STATUS, where STATUS can be - any of the values your bugzilla configuration allows as status. Be - aware, that changing a bug from any status for open bugs to a status - for closed bugs will not work, as the resolution would be missing. - resolution RESOLUTION - change the associated bug's resolution to RESOLUTION, where - RESOLUTION can be any of the values your bugzilla configuration - allows as resolution. Setting the resolution has only an effect if - the associated bug is in a closed state. - status/resolution STATUS/RESOLUTION - change the associated bug's status to STATUS and resolution to - RESOLUTION, where STATUS can be any of the values your bugzilla - configuration allows to close bugs, and RESOLUTION can be any of the - values your bugzilla configuration allows as resolution. -`<change-action>` -: Action performed on Gerrit change-id, possible values are: - `created, commented, merged, abandoned, restored` +[[config-rule-base]] +Rule base for Actions +~~~~~~~~~~~~~~~~~~~~~ -`<verified-value>` -: Verified flag added on Gerrit with values from -1 to +1 - For positive values, you must not omit a leading +. +In this part we describe, how to specify which events in gerrit (E.g.: +“Change Merged”, or “User ‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a +change”) should causes what action (e.g.: “Set issue's status to +‘Resolved’”) on the ITS. -`<code-review-value>` -: Code-Review flag added on Gerrit with values from -2 to +2 - For positive values, you must not omit a leading +. +Actions on the ITS and conditions for the action to take place are +configured through the rule base in `etc/its/actions.config` in the +site directory. The rule base is a git config file, and may contain an +arbirary number of rules. Each rule can have an arbitrary number of +conditions and actions. A rule fires all associated actions, once all +of its conditions are met. -Note: multiple conditions in the action stanza are optional but at least one must be present. +A simple `etc/its/actions.config` may look like +---- +[rule "rule1"] + event-type = change-merged + action = add-standard-comment +[rule "rule2"] + event-type = comment-added + approval-Code-Review = -2,-1 + action = add-comment Oh my Goodness! Someone gave a negative code review in gerrit on an associated change. +---- -Example: +This snippet defines two rules ('rule1', and 'rule2'). On merging a +change that's associated to some issues, 'rule1' adds a predefined +standard comment for “Change Merge” to each such issue. If someone +adds a comment to a change that is associated to some issues and votes +“-2”, or “-1” for “Code-Review”, 'rule2' adds the comment “Oh my +Goodness! Someone gave a negative code review in gerrit on an +associated change.” to each such issue. - [action "Start Progress"] - change=created +The order of rules in `etc/its/action.config` need not be +respected. So in the above example, do not rely on 'rule1' being +evaluated before 'rule2'. - [action "Resolve Issue"] - verified=+1 - code-review=+2 +Rules +~~~~~ - [action "Close Issue"] - change=merged +Each rule consists of three items: A name, a set of conditions, and a +set of actions. - [action "Stop Progress"] - change=abandoned +A rule's name ('rule1', and 'rule2' in the above example) are +currently not used and only provided for convenience. -The above example defines four status transition on Jira, based on the following conditions: +Each rule line setting the option 'action' is interpreted as +action. Any other lines of a rule are considered a condition. -* Whenever a new Change-set is created on Gerrit, start progress on the Jira issue -* Whenever a change is verified and reviewed with +2, transition the Jira issue to resolved -* Whenever a change is merged to branch, mark the Jira transition the Jira issue to closed -* Whenever a change is abandoned, stop the progress on Jira issue \ No newline at end of file +Each of a rule's actions is taken for events that meet all of a +rule's conditions. If a rule contains more than one action +specifications, the order in which they are given need not be +respected. + +There is no upper limit on the number of elements in a rules set of +conditions, and set of actions. Each of those sets may be empty. + +Conditions +~~~~~~~~~~ + +The conditions are lines of the form +---- +name = value1, value2, ..., valueN +---- +and (if 'value1' is not +!+) match if the event comes with a property +'name' having 'value1', or 'value2', or ..., or 'valueN'. So for +example to match events that come with an 'association' property +having 'subject', or 'footer-Bug', the following condition can be +used: +---- +association = subject,footer-Bug +---- + +If 'value1' is +!+, the conditon matches if the event does not come +with a property 'name' having 'value2', or ..., or 'valueN'. So for +example to match events that do not come with a 'status' property +having 'DRAFT', the following condition can be used: +---- +status = !,DRAFT +---- + +[[event-properties]] +Event Properties +~~~~~~~~~~~~~~~~ + +The properties exposed by events depend on the kind of event. + +For all events, the event's class name is provided in the 'event' +property. Most native gerrit events provide the 'event-type' +property. So 'event-type' (or 'event' for other events fired by +plugins) allows you to write filters that fire only for a certain type +of event. + +The common properties for each event are + +'event':: + The event's class name. +'issue':: + Issue to which this event is associated. Each event is associated to + exactly one issue. If for example an event is fired for a commit + message, that would contain more than one issue id (say issue “23”, + and issue “47"), then the event is duplicated and sent once for each + associated issue (i.e.: once with 'issue' being +23+, and once with + 'issue' being +47+). +'association':: + How the issue of property 'issue' got associated to this event. An + event typically has several 'association' properties. Possible + values are: + 'somewhere'::: issue id occurs somewhere in the commit message of the + change/the most recent patch set. + 'subject'::: issue id occurs in the first line of the commit message + of the change/the most recent patch set. + 'body'::: issue id occurs after the subject but before the footer + of the commit message of the change/the most recent patch set. + 'footer'::: issue id occurs in the last paragraph after the subject + of the commit message of the change/the most recent patch set. + 'footer-<Key>'::: issue id occurs in the footer of the commit + message of the change/the most recent patch set, and is in a line + with a key (part before the colon). + + + So for example, if the footer would contain a line ++ +---- +Fixes-Issue: issue 4711 +---- ++ +then a property 'association' with value +footer-Fixes-Issue+ would +get added to the event for issue “4711”. + + 'added@<Association-Value>'::: + (only for events that allow to determine the patch set number. So + for example, this 'association' property is not set for + RevUpdatedEvents) + + + issue id occurs at '<Association-Value>' in the most recent patch + set of the change, and either the event is for patch set 1 or the + issue id does not occur at '<Association-Value>' in the previous + patch set. + + + So for example if issue “4711” occurs in the subject of patch set + 3 (the most recent patch set) of a change, but not in patch set 2. + When adding a comment to this change, the event for issue “4711” + would get a property 'association' with value +added@subject+. + +The further properties are listed in the event's +corresponding subsection below: + +* <<event-properties-ChangeAbandonedEvent,ChangeAbandonedEvent>> +* <<event-properties-ChangeMergedEvent,ChangeMergedEvent>> +* <<event-properties-ChangeRestoredEvent,ChangeRestoredEvent>> +* <<event-properties-CommentAddedEvent,CommentAddedEvent>> +* <<event-properties-DraftPublishedEvent,DraftPublishedEvent>> +* <<event-properties-PatchSetCreatedEvent,PatchSetCreatedEvent>> +* <<event-properties-RefUpdatedEvent,RefUpdatedEvent>> +* <<event-properties-change,Common properties for events on a change>> +* <<event-properties-patch-set,Common properties for events on a patch set>> + +[[event-properties-ChangeAbandonedEvent]] +ChangeAbandonedEvent +^^^^^^^^^^^^^^^^^^^^ + +'abandoner-email':: + email address of the user abandoning the change. +'abandoner-name':: + name of the user abandoning the change. +'abandoner-username':: + username of the user abandoning the change. +'event':: + +com.google.gerrit.server.events.ChangeAbandonedEvent+ +'event-type':: + +change-abandoned+ +'reason':: + reason why the change has been abandoned. + +In addition to the above properties, the event also provides +properties for the abandoned <<event-properties-change,change>>, and +it's most recent <<event-properties-patch-set,patch set>>. + +[[event-properties-ChangeMergedEvent]] +ChangeMergedEvent +^^^^^^^^^^^^^^^^^^^ + +'event':: + +com.google.gerrit.server.events.ChangeMergedEvent+ +'event-type':: + +change-merged+ +'submitter-email':: + email address of the user causing the merge of the change. +'submitter-name':: + name of the user causing the merge of the change. +'submitter-username':: + username of the user causing the merge of the change. + +In addition to the above properties, the event also provides +properties for the merged <<event-properties-change,change>>, and +it's most recent <<event-properties-patch-set,patch set>>. + +[[event-properties-ChangeRestoredEvent]] +ChangeRestoredEvent +^^^^^^^^^^^^^^^^^^^ + +'event':: + +com.google.gerrit.server.events.ChangeRestoredEvent+ +'event-type':: + +change-restored+ +'reason':: + reason why the change has been restored. +'restorer-email':: + email address of the user restoring the change. +'restorer-name':: + name of the user restoring the change. +'restorer-username':: + username of the user restoring the change. + +In addition to the above properties, the event also provides +properties for the restored <<event-properties-change,change>>, and +it's most recent <<event-properties-patch-set,patch set>>. + +[[event-properties-CommentAddedEvent]] +CommentAddedEvent +^^^^^^^^^^^^^^^^^ + +NOTE: For consistency with the other events, the 'author-...' +properties of the CommentAddedEvent do not refer to the author of the +comment, but refer to the author of the change's latest patch set. The +author of the comment is accessible via the 'commenter-...' +properties. + +'commenter-email':: + email address of the comment's author. +'commenter-name':: + name of the comment's author. +'commenter-username':: + username of the comment's author. +'comment':: + added comment itself. +'event':: + +com.google.gerrit.server.events.CommentAddedEvent+ +'event-type':: + +comment-added+ + +For each new or changed approval that has been made for this change, a +property of key 'approval-<LabelName>' and the approval's value as +value is added. So for example voting “-2” for the approval +“Code-Review” would add the following property: + +'approval-Code-Review':: + +-2+ + +In addition to the above properties, the event also provides +properties for the <<event-properties-change,change>> the comment was +added for, and it's most recent <<event-properties-patch-set,patch +set>>. + +[[event-properties-DraftPublishedEvent]] +DraftPublishedEvent +^^^^^^^^^^^^^^^^^^^ + +'event':: + +com.google.gerrit.server.events.DraftPublishedEvent+ +'event-type':: + +draft-published+ + +In addition to the above properties, the event also provides +properties for the uploaded <<event-properties-patch-set,patch set>>, +and the <<event-properties-change,change>> it belongs to. + +[[event-properties-PatchSetCreatedEvent]] +PatchSetCreatedEvent +^^^^^^^^^^^^^^^^^^^ + +'event':: + +com.google.gerrit.server.events.PatchSetCreatedEvent+ +'event-type':: + +patchset-created+ + +In addition to the above properties, the event also provides +properties for the uploaded <<event-properties-patch-set,patch set>>, +and the <<event-properties-change,change>> it belongs to. + +[[event-properties-RefUpdatedEvent]] +RefUpdatedEvent +^^^^^^^^^^^^^^^ + +'event':: + +com.google.gerrit.server.events.RefUpdatedEvent+ +'event-type':: + +ref-updated+ +'project':: + full name of the project from which a ref was updated. +'ref':: + git ref that has been updated (Typcially the branch, as for example + +master+). +'revision':: + git commit hash the rev is pointing to now. +'revision-old':: + git commit hash the rev was pointing to before. +'submitter-email':: + email address of the user that updated the ref. +'submitter-name':: + name of the user that updated the ref. +'submitter-username':: + username of the user that updated the ref. + +[[event-properties-change]] +Common properties for events on a change +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +'branch':: + name of the branch the change belongs to. +'change-id':: + Change-Id for the change („I-followed by 40 hex digits” string). +'change-number':: + number for the change (plain integer). +'change-url':: + url of the change. +'owner-email':: + email address of the change's owner. +'owner-name':: + name of the change's owner. +'owner-username':: + username of the change's owner. +'project':: + full name of the project the change belongs to. +'subject':: + first line of the change's most recent patch set's commit message. +'status':: + status of the change ('null', 'NEW', 'SUBMITTED', 'DRAFT', 'MERGED', + or 'ABANDONED' ) + + + This property will typically be 'null' unless the used gerrit + incorporates + https://gerrit-review.googlesource.com/#/c/47042/[upstream change + 47042]. +'topic':: + name of the topic the change belongs to. + +[[event-properties-patch-set]] +Common properties for events on a patch set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +'author-email':: + email address of this patch set's author. +'author-name':: + name of this patch set's author. +'author-username':: + username of this patch set's author. +'created-on':: + Timestamp of creation of the patch set (Seconds since 1st January 1970). +'deletions':: + number of lines deleted by the patch set. +'insertions':: + number of lines inserted by the patch set. +'is-draft':: + 'true', if the patch set is a draft patch set, 'false' otherwise. +'parents':: + A list of git commit hashes that are parents to the patch set. +'patch-set-number':: + patch set's number within the change. +'ref':: + git ref for the patch set (For the 5-th patch set of change 4711, this + will be +refs/changes/11/4711/5+). +'revision':: + git commit hash of the patch set +'uploader-email':: + email address of the user that uploaded this patch set. +'uploader-name':: + name of the user that uploaded this patch set. +'uploader-username':: + username of the user that uploaded this patch set. + +Actions +~~~~~~~ + +Lines of the form +---- +action = name param1 param2 ... paramN +---- +represent the action 'name' being called with parameters 'param1', +'param2', ... 'paramN'. + +The following actions are available: + +<<action-add-comment,add-comment>>:: + adds the parameters as issue comment +<<action-add-standard-comment,add-standard-comment>>:: + adds a predefined standard comment for certain events +<<action-add-velocity-comment,add-velocity-comment>>:: + adds a rendered Velocity template as issue comment. +<<action-log-event,log-event>>:: + appends the event's properties to gerrit's log. +<<action-resolution,resolution>>:: + sets the resolution of the issue +<<action-status,status>>:: + sets the status of the issue +<<action-status-resolution,status/resolution>>:: + sets the status of the issue + +Further actions may be provided by 'hooks-its' based plugins. + +[[action-add-comment]] +Action: add-comment +^^^^^^^^^^^^^^^^^^^ + +The 'add-comment' action adds the given parameters as comment to any associated rule. + +So for example +---- +action = add-comment This is a sample command +---- +would add a comment “This is a sample command” to associated issues. + +If no parameters are given, no comment gets added. + +[[action-add-standard-comment]] +Action: add-standard-comment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The 'add-standard-comment' action adds predefined comments to +associated issues for change abandoned, merged, restored, and patch +set created events. For other events, no comment is added to the +associated issues. + +The added comments contain the person responsible for the event +(abandoner, merger, ...), the change's subject, a reason (if one has +been given), and a link to the change. + +[[action-add-velocity-comment]] +Action: add-velocity-comment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The 'add-velocity-comment' action renders a Velocity template for the +event and adds the output as comment to any associated issue. + +So for example +---- +action = add-velocity-comment TemplateName +---- +would render the template `etc/its/templates/TemplateName.vm` add the +output as comment to associated issues. + +If 'TemplateName' is “inline”, the Velocity template to render is not +loaded from a file, but the template is built by joining the remaining +parameters. So for example +---- +action = add-velocity-comment inline Sample template using $subject property. +---- +would render “Sample template using $subject property.” as Velocity +template. + +If 'TemplateName' is not “inline”, further parameters get ignored. + +Any <<event-properties,property>> of the event may be used from +templates. So for example +$subject+ in the above example refers to +the event's subject property, and +$change-number+ would refer to the +change's number. + +Additionally, the context's 'its' property provides an object that +allows to format links using the its' syntax: + +'formatLink( url )':: + Formats a link to a url. + + + So for example upon adding a comment to a change, the following rule + formats a link to the change: ++ +---- +[rule "formatLinkSampleRule"] + event-type = comment-added + action = add-velocity-comment inline Comment for change $change-number added. See ${its.formatLink($change-url)} +---- + +'formatLink( url, caption )':: + Formats a link to a url using 'caption' to represent the url. + + + So for example upon adding a comment to a change, the following rule + formats a link to the change using the change number as link + capition: ++ +---- +[rule "formatLinkSampleRule"] + event-type = comment-added + action = add-velocity-comment inline Comment for change ${its.formatLink($change-url, $change-number)} added. +----- + +[[action-log-event]] +Action: log-event +^^^^^^^^^^^^^^^^^ + +The 'log-event' action appends the event's properties to gerrit's log. + +Logging happens at the info level per default, but can be overriden by +adding the desired log level as parameter. Supported values are +'error', 'warn', 'info', and 'debug'). So for example +---- +action = log-event error +---- +appends the event's properties to gerrit's log at error level. All +other parameters are ignored. + +This action is useful, when testing rules or trying to refine +conditions on rules, as it make the available properties visible. + +[[action-resolution]] +Action: resolution +^^^^^^^^^^^^^^^^^^ + +The 'resolution' action sets the issue's resolution. The first parameter is +the resolution to set. So for example +---- +action = resolution WORKSFORME +---- +sets the issue's status to WORKSFORME. + +If you want to set the status and the resolution, use the +'status/resolution' action, so you can set both status and resolution +in one go. + +[[action-status]] +Action: status +^^^^^^^^^^^^^^ + +The 'status' action sets the issue's status. The first parameter is +the status to set. So for example +---- +action = status CONFIRMED +---- +sets the issue's status to CONFIRMED. + +If you want to set the status to a value that also requires a +resolution, use the 'status/resolution' action, so you can set both +status and resolution in one go. + +[[action-status-resolution]] +Action: status/resolution +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The 'status/resolution' action sets both the issue's status and it's +resolution in one go. The first parameter is of the form +'STATUS/RESOLUTION' and sets the status to 'STATUS' and the resolution +to 'RESOLUTION'. + +So for example +---- +action = status/resolution RESOLVED/FIXED +---- +sets the issue's status to RESOLVED and it's resolution to FIXED. 